.TH "UNICORN" "3" "Jan 27th 2025" "Unicorn 1.0.4"
.SH NAME
uni_collate \- compare strings for sorting
.SH LIBRARY
Embeddable Unicode Algorithms (libunicorn, -lunicorn)
.SH SYNOPSIS
.nf
.B #include <unicorn.h>
.PP
.BI "unistat uni_collate(const void *" s1 ", unisize " s1_len ", uniattr " s1_attr ", const void *" s2 ", unisize " s2_len ", uniattr " s2_attr ", uniweighting " weighting ", unistrength " strength ", int32_t *" result ");"
.fi
.SH DESCRIPTION
Compare strings \f[I]s1\f[R] and \f[I]s2\f[R] and write -1, 0, or 1 to \f[I]result\f[R] depending on if \f[C]s1 < s2\f[R], \f[C]s1 = s2\f[R], or \f[C]s1 > s2\f[R].
.PP
The length and text attributes for \f[I]s1\f[R] are specified by \f[I]s1_len\f[R] and \f[I]s1_attr\f[R].
The length and text attributes for \f[I]s2\f[R] are specified by \f[I]s2_len\f[R] and \f[I]s2_attr\f[R].
If \f[I]s1_len\f[R] is \f[C]-1\f[R], then the implementation assumes \f[I]s1\f[R] is null terminated.
If \f[I]s2_len\f[R] is \f[C]-1\f[R], then the implementation assumes \f[I]s2\f[R] is null terminated.
.PP
This function is intended for one-off string comparisons.
If a string will be compared multiple times, then it’s recommended to construct a sort key once with \f[B]uni_sortkeymk\f[R](3) and compare with \f[B]uni_sortkeycmp\f[R](3).
.PP
Support for collation must be enabled in the JSON configuration file.
.PP
.in +4n
.EX
{
    "algorithms": {
        "collation": true
    }
}
.EE
.in
.SH RETURN VALUE
.TP
UNI_OK
On success.
.TP
UNI_BAD_OPERATION
If \f[I]s1\f[R] or \f[I]s2\f[R] are \f[C]NULL\f[R], or if \f[I]result\f[R] is \f[C]NULL\f[R].
.TP
UNI_BAD_ENCODING
If \f[I]s1\f[R] or \f[I]s2\f[R] is not well-formed (checks are omitted if the corresponding \f[B]uniattr\f[R](3) has \f[B]UNI_TRUST\f[R](3)).
.TP
UNI_FEATURE_DISABLED
If Unicorn was built without support for collation.
.TP
UNI_NO_MEMORY
If dynamic memory allocation failed.
.SH SEE ALSO
.BR uni_sortkeymk (3),
.BR uni_sortkeycmp (3),
.BR uniweighting (3),
.BR unistrength (3),
.BR uniattr (3),
.BR UNI_TRUST (3),
.BR unisize (3)
.SH AUTHOR
.UR https://railgunlabs.com
Railgun Labs
.UE .
.SH INTERNET RESOURCES
The online documentation is published on the
.UR https://railgunlabs.com/unicorn
Railgun Labs website
.UE .
.SH LICENSING
Unicorn is distributed with its end-user license agreement (EULA).
Please review the agreement for information on terms & conditions for accessing or otherwise using Unicorn and for a DISCLAIMER OF ALL WARRANTIES.
